GetPromiseValue

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods / ODStorageUnit

GetPromiseValue
The GetPromiseValue method reads promise data from the specified value of the currently focused property.
ODULong GetPromiseValue (in ODValueType valueType,
                         in ODULong offset,
                         in ODULong length,
                         out ODByteArray value,
                         out ODPart sourcePart);
valueType
The type of the value from which the promise data is to be read.
offset
The offset from which the promise data is to be retrieved, expressed as an unsigned 32-bit number of bytes from the beginning of the value.
length
The length (in bytes) of the data to be retrieved, expressed as an unsigned 32-bit value.
value
A byte array structure to contain the retrieved promise data.
sourcePart
A reference to the part that made the promise.
return value
The number of bytes read, expressed as an unsigned 32-bit value.

DISCUSSION
You call this method to read promise data without fulfilling the promise. This method first focuses the storage unit on the specified value of the currently focused property. It then starts reading data at the specified offset and stops after reading the number of bytes specified by the length parameter or after reaching the end of the data in the focused value, whichever comes first.
When you call this method, the _buffer field of the value output parameter should be kODNULL; if it isn't, the buffer to which that field points will not be deallocated.
This method sets the _buffer field of the value output parameter to point to a memory block containing the promise data, the _maximum field to the specified length, and the _length field to the number of bytes actually read.
This method sets the sourcePart output parameter to a reference to the part that made the promise. This method does not increment the reference count of the part that made the promise.
When you no longer need the structure you pass as the value parameter, you should deallocate that structure and its buffer.

EXCEPTIONS

kODErrInvalidValueType
The specified value type is improperly formed or illegal.
kODErrSUValueDoesNotExist
This currently focused property does not have a value with the specified value type.
kODErrUnfocusedStorageUnit
This storage unit is not focused on a property or a value.
kODErrZeroRefCount
This storage unit has a reference count of 0.

SEE ALSO
The ODByteArray type (page 877).
The ODValueType type (page 904).
The ODStorageUnit::IsPromiseValue method (page 703).
The ODStorageUnit::SetPromiseValue method (page 711).